Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations #142252

fu5ha · 2025-06-09T17:02:06Z

Motivation

The existing documentation for atomic fetch_update (and other similar methods) has a section that reads like so:

Considerations

This method is not magic; it is not provided by the hardware. It is implemented in
terms of AtomicBlah::compare_exchange_weak, and suffers from the same drawbacks.
In particular, this method will not circumvent the ABA Problem.

The wording here seems to imply that the drawbacks being discusses are caused by the weak version of compare_exchange, and that one may avoid those drawbacks by using compare_exchange instead. Indeed, a conversation in the #dark-arts channel on the Rust community discord based on this interpretation led to this PR.

In reality, the drawbacks are inherent to implementing such an operation based on any compare-and-swap style operation, as opposed to an LL,SC operation, and they apply equally to compare_exchange and compare_exchange_weak as well.

Changes

Rewords existing Considerations section on fetch_update and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of compare_exchange in particular. New version:

Considerations

This method is not magic; it is not provided by the hardware, and does not act like a
critical section or mutex.

It is implemented on top of an atomic compare-and-swap operation, and thus is subject to
the usual drawbacks of CAS operations. In particular, be careful of the ABA problem
if this atomic integer is an index or more generally if knowledge of only the bitwise value
of the atomic is not in and of itself sufficient to ensure any required preconditions.

Add Considerations to compare_exchange and compare_exchange_weak which details similar considerations and when they may be relevant. New version:

Considerations

compare_exchange is a compare-and-swap operation and thus exhibits the usual downsides
of CAS operations. In particular, a load of the value followed by a successful
compare_exchange with the previous load does not ensure that other threads have not
changed the value in the interim. This is usually important when the equality check in
the compare_exchange is being used to check the identity of a value, but equality
does not necessarily imply identity. In this case, compare_exchange can lead to the
ABA problem.

rustbot · 2025-06-09T17:02:10Z

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

ibraheemdev · 2025-06-09T18:39:40Z

library/core/src/sync/atomic.rs

+    /// [`compare_exchange`][Self::compare_exchange]\*, which is a [CAS operation], and thus
+    /// suffers from the usual drawbacks of CAS operations, in particular the [ABA problem].
+    ///
+    /// \* It is actually implemented using [`compare_exchange_weak`][Self::compare_exchange_weak],


I don't think the strong vs. weak CAS is observable behavior for fetch_update. Given that I'm inclined to remove this note and just mention compare_exchange_weak in the previous paragraph, now that it clarifies that the drawbacks are linked to the use of CAS, not whether or not the CAS is weak or not.

ibraheemdev · 2025-06-10T15:05:16Z

Thanks. @bors r+

bors · 2025-06-10T15:05:19Z

📌 Commit 6c55fba has been approved by ibraheemdev

It is now in the queue for this repository.

ibraheemdev · 2025-06-10T15:05:26Z

@bors rollup

- Rewords existing Considerations section on `fetch_update` and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of `compare_exchange` in particular - Add Considerations to `compare_exchange` and `compare_exchange_weak` which details similar considerations and when they may be relevant.

fu5ha · 2025-06-10T15:14:50Z

@ibraheemdev you were too fast! I pushed one more update, with a tiny formatting/grammar fix. Thanks for the review!

ibraheemdev · 2025-06-11T20:30:44Z

@bors r+ rollup

bors · 2025-06-11T20:30:46Z

📌 Commit 2095211 has been approved by ibraheemdev

It is now in the queue for this repository.

Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations ## Motivation The existing documentation for atomic `fetch_update` (and other similar methods) has a section that reads like so: > ### Considerations > This method is not magic; it is not provided by the hardware. It is implemented in > terms of `AtomicBlah::compare_exchange_weak`, and suffers from the same drawbacks. > In particular, this method will not circumvent the [ABA Problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem The wording here seems to imply that the drawbacks being discusses are caused by the *`weak` version* of `compare_exchange`, and that one may avoid those drawbacks by using `compare_exchange` instead. Indeed, a conversation in the `#dark-arts` channel on the Rust community discord based on this interpretation led to this PR. In reality, the drawbacks are inherent to implementing such an operation based on *any* compare-and-swap style operation, as opposed to an [LL,SC](https://en.wikipedia.org/wiki/Load-link/store-conditional) operation, and they apply equally to `compare_exchange` and `compare_exchange_weak` as well. ## Changes - Rewords existing Considerations section on `fetch_update` and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of `compare_exchange` in particular. New version: > ### Considerations > > This method is not magic; it is not provided by the hardware, and does not act like a > critical section or mutex. > > It is implemented on top of an atomic [compare-and-swap operation], and thus is subject to > the usual drawbacks of CAS operations. In particular, be careful of the [ABA problem] > if this atomic integer is an index or more generally if knowledge of only the *bitwise value* > of the atomic is not in and of itself sufficient to ensure any required preconditions. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap - Add Considerations to `compare_exchange` and `compare_exchange_weak` which details similar considerations and when they may be relevant. New version: > ### Considerations > > `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides > of CAS operations. In particular, a load of the value followed by a successful > `compare_exchange` with the previous load *does not ensure* that other threads have not > changed the value in the interim. This is usually important when the *equality* check in > the `compare_exchange` is being used to check the *identity* of a value, but equality > does not necessarily imply identity. In this case, `compare_exchange` can lead to the > [ABA problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap

Rollup of 9 pull requests Successful merges: - #138016 (Added `Clone` implementation for `ChunkBy`) - #140770 (add `extern "custom"` functions) - #141162 (refactor `AttributeGate` and `rustc_attr!` to emit notes during feature checking) - #141474 (Add `ParseMode::Diagnostic` and fix multiline spans in diagnostic attribute lints) - #141947 (Specify that "option-like" enums must be `#[repr(Rust)]` to be ABI-compatible with their non-1ZST field.) - #142135 (docs: autogenerate compiler flag stubs based on -Zhelp) - #142252 (Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations) - #142337 (miri: add flag to suppress float non-determinism) - #142353 (compiler: Ease off the accelerator on `unsupported_calling_conventions`) r? `@ghost` `@rustbot` modify labels: rollup

Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations ## Motivation The existing documentation for atomic `fetch_update` (and other similar methods) has a section that reads like so: > ### Considerations > This method is not magic; it is not provided by the hardware. It is implemented in > terms of `AtomicBlah::compare_exchange_weak`, and suffers from the same drawbacks. > In particular, this method will not circumvent the [ABA Problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem The wording here seems to imply that the drawbacks being discusses are caused by the *`weak` version* of `compare_exchange`, and that one may avoid those drawbacks by using `compare_exchange` instead. Indeed, a conversation in the `#dark-arts` channel on the Rust community discord based on this interpretation led to this PR. In reality, the drawbacks are inherent to implementing such an operation based on *any* compare-and-swap style operation, as opposed to an [LL,SC](https://en.wikipedia.org/wiki/Load-link/store-conditional) operation, and they apply equally to `compare_exchange` and `compare_exchange_weak` as well. ## Changes - Rewords existing Considerations section on `fetch_update` and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of `compare_exchange` in particular. New version: > ### Considerations > > This method is not magic; it is not provided by the hardware, and does not act like a > critical section or mutex. > > It is implemented on top of an atomic [compare-and-swap operation], and thus is subject to > the usual drawbacks of CAS operations. In particular, be careful of the [ABA problem] > if this atomic integer is an index or more generally if knowledge of only the *bitwise value* > of the atomic is not in and of itself sufficient to ensure any required preconditions. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap - Add Considerations to `compare_exchange` and `compare_exchange_weak` which details similar considerations and when they may be relevant. New version: > ### Considerations > > `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides > of CAS operations. In particular, a load of the value followed by a successful > `compare_exchange` with the previous load *does not ensure* that other threads have not > changed the value in the interim. This is usually important when the *equality* check in > the `compare_exchange` is being used to check the *identity* of a value, but equality > does not necessarily imply identity. In this case, `compare_exchange` can lead to the > [ABA problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap

Rollup of 8 pull requests Successful merges: - #138016 (Added `Clone` implementation for `ChunkBy`) - #140770 (add `extern "custom"` functions) - #141162 (refactor `AttributeGate` and `rustc_attr!` to emit notes during feature checking) - #141474 (Add `ParseMode::Diagnostic` and fix multiline spans in diagnostic attribute lints) - #141947 (Specify that "option-like" enums must be `#[repr(Rust)]` to be ABI-compatible with their non-1ZST field.) - #142252 (Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations) - #142337 (miri: add flag to suppress float non-determinism) - #142353 (compiler: Ease off the accelerator on `unsupported_calling_conventions`) r? `@ghost` `@rustbot` modify labels: rollup

Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations ## Motivation The existing documentation for atomic `fetch_update` (and other similar methods) has a section that reads like so: > ### Considerations > This method is not magic; it is not provided by the hardware. It is implemented in > terms of `AtomicBlah::compare_exchange_weak`, and suffers from the same drawbacks. > In particular, this method will not circumvent the [ABA Problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem The wording here seems to imply that the drawbacks being discusses are caused by the *`weak` version* of `compare_exchange`, and that one may avoid those drawbacks by using `compare_exchange` instead. Indeed, a conversation in the `#dark-arts` channel on the Rust community discord based on this interpretation led to this PR. In reality, the drawbacks are inherent to implementing such an operation based on *any* compare-and-swap style operation, as opposed to an [LL,SC](https://en.wikipedia.org/wiki/Load-link/store-conditional) operation, and they apply equally to `compare_exchange` and `compare_exchange_weak` as well. ## Changes - Rewords existing Considerations section on `fetch_update` and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of `compare_exchange` in particular. New version: > ### Considerations > > This method is not magic; it is not provided by the hardware, and does not act like a > critical section or mutex. > > It is implemented on top of an atomic [compare-and-swap operation], and thus is subject to > the usual drawbacks of CAS operations. In particular, be careful of the [ABA problem] > if this atomic integer is an index or more generally if knowledge of only the *bitwise value* > of the atomic is not in and of itself sufficient to ensure any required preconditions. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap - Add Considerations to `compare_exchange` and `compare_exchange_weak` which details similar considerations and when they may be relevant. New version: > ### Considerations > > `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides > of CAS operations. In particular, a load of the value followed by a successful > `compare_exchange` with the previous load *does not ensure* that other threads have not > changed the value in the interim. This is usually important when the *equality* check in > the `compare_exchange` is being used to check the *identity* of a value, but equality > does not necessarily imply identity. In this case, `compare_exchange` can lead to the > [ABA problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap

Rollup of 7 pull requests Successful merges: - #138016 (Added `Clone` implementation for `ChunkBy`) - #141162 (refactor `AttributeGate` and `rustc_attr!` to emit notes during feature checking) - #141474 (Add `ParseMode::Diagnostic` and fix multiline spans in diagnostic attribute lints) - #141947 (Specify that "option-like" enums must be `#[repr(Rust)]` to be ABI-compatible with their non-1ZST field.) - #142252 (Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations) - #142337 (miri: add flag to suppress float non-determinism) - #142353 (compiler: Ease off the accelerator on `unsupported_calling_conventions`) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 6 pull requests Successful merges: - #138016 (Added `Clone` implementation for `ChunkBy`) - #141162 (refactor `AttributeGate` and `rustc_attr!` to emit notes during feature checking) - #141474 (Add `ParseMode::Diagnostic` and fix multiline spans in diagnostic attribute lints) - #141947 (Specify that "option-like" enums must be `#[repr(Rust)]` to be ABI-compatible with their non-1ZST field.) - #142252 (Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations) - #142337 (miri: add flag to suppress float non-determinism) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #142252 - fu5ha:doc-cas-ops, r=ibraheemdev Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations ## Motivation The existing documentation for atomic `fetch_update` (and other similar methods) has a section that reads like so: > ### Considerations > This method is not magic; it is not provided by the hardware. It is implemented in > terms of `AtomicBlah::compare_exchange_weak`, and suffers from the same drawbacks. > In particular, this method will not circumvent the [ABA Problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem The wording here seems to imply that the drawbacks being discusses are caused by the *`weak` version* of `compare_exchange`, and that one may avoid those drawbacks by using `compare_exchange` instead. Indeed, a conversation in the `#dark-arts` channel on the Rust community discord based on this interpretation led to this PR. In reality, the drawbacks are inherent to implementing such an operation based on *any* compare-and-swap style operation, as opposed to an [LL,SC](https://en.wikipedia.org/wiki/Load-link/store-conditional) operation, and they apply equally to `compare_exchange` and `compare_exchange_weak` as well. ## Changes - Rewords existing Considerations section on `fetch_update` and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of `compare_exchange` in particular. New version: > ### Considerations > > This method is not magic; it is not provided by the hardware, and does not act like a > critical section or mutex. > > It is implemented on top of an atomic [compare-and-swap operation], and thus is subject to > the usual drawbacks of CAS operations. In particular, be careful of the [ABA problem] > if this atomic integer is an index or more generally if knowledge of only the *bitwise value* > of the atomic is not in and of itself sufficient to ensure any required preconditions. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap - Add Considerations to `compare_exchange` and `compare_exchange_weak` which details similar considerations and when they may be relevant. New version: > ### Considerations > > `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides > of CAS operations. In particular, a load of the value followed by a successful > `compare_exchange` with the previous load *does not ensure* that other threads have not > changed the value in the interim. This is usually important when the *equality* check in > the `compare_exchange` is being used to check the *identity* of a value, but equality > does not necessarily imply identity. In this case, `compare_exchange` can lead to the > [ABA problem]. > > [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem > [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap

Rollup of 6 pull requests Successful merges: - rust-lang/rust#138016 (Added `Clone` implementation for `ChunkBy`) - rust-lang/rust#141162 (refactor `AttributeGate` and `rustc_attr!` to emit notes during feature checking) - rust-lang/rust#141474 (Add `ParseMode::Diagnostic` and fix multiline spans in diagnostic attribute lints) - rust-lang/rust#141947 (Specify that "option-like" enums must be `#[repr(Rust)]` to be ABI-compatible with their non-1ZST field.) - rust-lang/rust#142252 (Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations) - rust-lang/rust#142337 (miri: add flag to suppress float non-determinism) r? `@ghost` `@rustbot` modify labels: rollup

rustbot assigned ibraheemdev Jun 9, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 9, 2025

ibraheemdev reviewed Jun 9, 2025

View reviewed changes

fu5ha force-pushed the doc-cas-ops branch from f019c4d to 6c55fba Compare June 10, 2025 15:01

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 10, 2025

fu5ha force-pushed the doc-cas-ops branch from 6c55fba to 2095211 Compare June 10, 2025 15:14

workingjubilee mentioned this pull request Jun 12, 2025

Rollup of 15 pull requests #142396

Closed

workingjubilee mentioned this pull request Jun 12, 2025

Rollup of 15 pull requests #142397

Closed

matthiaskrgr mentioned this pull request Jun 12, 2025

Rollup of 9 pull requests #142399

Closed

matthiaskrgr mentioned this pull request Jun 12, 2025

Rollup of 8 pull requests #142409

Closed

matthiaskrgr mentioned this pull request Jun 12, 2025

Rollup of 7 pull requests #142421

Closed

matthiaskrgr mentioned this pull request Jun 12, 2025

Rollup of 6 pull requests #142432

Merged

bors merged commit 764be85 into rust-lang:master Jun 13, 2025
10 checks passed

rustbot added this to the 1.89.0 milestone Jun 13, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations #142252

Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations #142252

fu5ha commented Jun 9, 2025 •

edited

Loading

Uh oh!

rustbot commented Jun 9, 2025

Uh oh!

ibraheemdev Jun 9, 2025 •

edited

Loading

Uh oh!

ibraheemdev commented Jun 10, 2025

Uh oh!

bors commented Jun 10, 2025

Uh oh!

ibraheemdev commented Jun 10, 2025

Uh oh!

fu5ha commented Jun 10, 2025

Uh oh!

ibraheemdev commented Jun 11, 2025

Uh oh!

bors commented Jun 11, 2025

Uh oh!

Uh oh!

Uh oh!

Improve clarity of core::sync::atomic docs about "Considerations" in regards to CAS operations #142252

Improve clarity of core::sync::atomic docs about "Considerations" in regards to CAS operations #142252

Conversation

fu5ha commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Considerations

Changes

Considerations

Considerations

Uh oh!

rustbot commented Jun 9, 2025

Uh oh!

ibraheemdev Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibraheemdev commented Jun 10, 2025

Uh oh!

bors commented Jun 10, 2025

Uh oh!

ibraheemdev commented Jun 10, 2025

Uh oh!

fu5ha commented Jun 10, 2025

Uh oh!

ibraheemdev commented Jun 11, 2025

Uh oh!

bors commented Jun 11, 2025

Uh oh!

Uh oh!

Uh oh!

Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations #142252

Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations #142252

fu5ha commented Jun 9, 2025 •

edited

Loading

ibraheemdev Jun 9, 2025 •

edited

Loading